.TH std::experimental::ranges::advance 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::experimental::ranges::advance \- std::experimental::ranges::advance

.SH Synopsis
   Defined in header <experimental/ranges/iterator>
   namespace {
                                                                   (ranges TS)
       constexpr /* unspecified */ advance = /* unspecified        (customization point
   */;                                                             object)

   }
   Call signature
   template< Iterator I >
   constexpr void advance( I& i, ranges::difference_type_t<I>  \fB(1)\fP
   n );
   template< Iterator I, Sentinel<I> S >                       \fB(2)\fP
   constexpr void advance( I& i, S bound );
   template< Iterator I, Sentinel<I> S >
   constexpr ranges::difference_type_t<I> advance( I& i,       \fB(3)\fP
   ranges::difference_type_t<I> n, S bound );

   Advances the iterator i n times, or until bound is reached, whichever comes first.

   1) If I models RandomAccessIterator, equivalent to i += n. Otherwise, increments (or
   decrements if n is negative) i n times. The behavior is undefined if n is negative
   and I does not model BidirectionalIterator.
   2) If Assignable<I&, S> is satisfied, equivalent to i = std::move(bound).
   Otherwise, if [i, bound) does not denote a range, the behavior is undefined.
   Otherwise, if SizedSentinel<S, I> is satisfied, equivalent to ranges::advance(i,
   bound - i).
   Otherwise, increments i until i == bound.
   3) If SizedSentinel<S, I> is satisfied, equivalent to ranges::advance(i, bound) if
   |n| >= |bound - i|, and ranges::advance(i, n) otherwise.
   Otherwise, increments (or decrements if n is negative) i either n times or until i
   == bound, whichever comes first.
   If n > 0, [i, bound) shall denote a range; if n == 0, either [i, bound) or
   [bound, i) shall denote a range; if n < 0, [bound, i) shall denote a range, I and S
   shall be the same type, and I must model BidirectionalIterator. Otherwise, the
   behavior is undefined.

.SH Return value

   1,2) \fI(none)\fP
   3) The number of increment/decrements not performed due to reaching bound. In other
   words, n - M, where M is the distance from the starting position of i to the ending
   position and is negative if the ending position is before the starting position.

.SH Example

    This section is incomplete
    Reason: no example

.SH See also

   advance  advances an iterator by given distance
            \fI(function template)\fP
            returns the distance between an iterator and a sentinel, or between the
   distance beginning and the end of a range
            \fI(function template)\fP
   next     increment an iterator
            \fI(function template)\fP
   prev     decrement an iterator
            \fI(function template)\fP

.SH Category:
     * Todo no example
